Closes #533.

What was wrong

getPayoutsOwed() read four whole relations — tenants, revenue_splits, transactions, payouts — with no .range() and no .limit(), then handed the arrays to computeOwedBalances(), which is pure arithmetic over whatever it is given.

PostgREST caps every response at the project's configured API "Max rows" and reports the cap exactly the way it reports a complete result: a 200 with fewer rows in it. Nothing downstream can tell them apart, so past the cap the balance simply comes out wrong, in whichever direction the truncation landed:

• transactions truncated → grossOwed too low → underpays the school
• payouts truncated → alreadyPaid too low → overpays it

And it was never display-only. markPayoutPaid() re-calls getPayoutsOwed() for its 10% mismatch guard, so a truncated balance also decided whether an operator got warned about a wrong payout amount — the guard would have waved through the very typo it exists to catch.

The tenants sweep in app/api/cron/enforce-plan-limits/route.ts had the same shape with a different symptom: past the cap the daily reconcile silently stopped visiting the tail of the tenant list, quietly disabling the only organic-growth trigger for #494's access cutoff.

The configured cap. supabase/config.toml sets max_rows = 1000 for the local stack. On the cloud project pg_db_role_setting holds no pgrst.* override, so it runs on Supabase's hosted default — also 1000. Both are now written down in docs/PLATFORM_ADMIN.md, but the fix is deliberately built not to depend on either being right.

What changed

lib/supabase/fetch-all-rows.ts (new). Pages a query until the relation is exhausted, then asserts the rows it actually collected against PostgREST's own count: 'exact' and throws — naming the relation and both numbers — when it comes up short. Callers must supply { count: 'exact' } (there is nothing to verify against otherwise) and a stable .order() on a unique column (unordered .range() windows can overlap or skip rows, which would trade a truncation bug for a duplication bug).

Two decisions worth reviewing:

• The assertion is deliberately asymmetric. Fewer rows than the count is an error; more is fine, because rows inserted while the sweep runs are benign. Treating growth as corruption would fail the platform payouts page whenever a sale lands mid-render.
• The loop self-tunes and never reads the cap. PostgREST clamps ranged requests too, so asking for a window wider than the cap returns a short page that is not the end of the relation — reading it as "done" would have reproduced the original bug inside the fix. Instead the loop adopts whatever page size the server proved it can return and continues from there. A MAX_PAGES ceiling stops a pathological server from spinning it forever.

app/actions/platform/payouts.ts — all four reads paged, each ordered by its primary key. Promise.all across the four relations is kept, so only pages within one relation serialize.

app/api/cron/enforce-plan-limits/route.ts — tenant sweep paged; an incomplete read now returns a 500 instead of quietly reconciling a partial list.

docs/PLATFORM_ADMIN.md — the rule, the confirmed cap, and the note that SQL-side aggregation (get_platform_stats, get_platform_revenue) remains immune by construction and is the better option for a large relation.

Why paging and not a SECURITY DEFINER aggregate

The issue offered either. An RPC would cut the transfer, but it would fork the arithmetic: lib/payments/payouts-owed.ts carries ~100 lines of documented, test-covered rules — the per-transaction split snapshot with its pre-#496 fallback, per-currency grouping, the reporting-only clawback heuristic, #516's overpaid term. Restating those in SQL creates two implementations that must agree forever, and the failure mode of them drifting is the same class of quiet wrongness this issue is about. Paging closes the correctness hole with one source of truth. If the transfer volume ever becomes the problem, the RPC is still available — that would be a performance change, made deliberately, not a correctness one.

Testing

• npm run test:unit — 354 passed / 30 files. 12 new cases for fetchAllRows (short page, empty relation, multi-page accumulation, exact-multiple boundary, server cap below the requested page size, unrecoverable shortfall throws, concurrent-insert growth does not, moving count ignored, page-2 error propagates with its offset, runaway ceiling, default page size). The 30 existing payouts-owed cases stay green — the arithmetic module is untouched.

• npm run typecheck — clean.

• npm run build — clean.

• npx eslint on changed files — 0 errors, 1 pre-existing unused-var warning in payouts.ts:13, untouched by this PR.

• Verified against real PostgREST, not a mock. Forced the local stack's cap to 5 rows (ALTER ROLE authenticator SET pgrst.db_max_rows = '5') and ran the real queries against a 20-row table:

  [1] bare .select() returned 5 rows, no error  <-- silent truncation
  [2] fetchAllRows returned 20 rows (20 unique) vs 20 expected
  [3] tenants: 7 rows, complete   revenue_splits: 1   transactions: 0   payouts: 0
  [4] shortfall surfaced: fetchAllRows(question_options): incomplete read — fetched 5 of 20 rows.
  

  Note line 2: the helper was still requesting 500-row pages against a cap of 5 and returned everything, unique and in order. The cap was reset afterwards (pg_db_role_setting verified empty) and the throwaway script is not part of this branch.

QA script

No UI changed, so there is nothing visual to compare — the platform payouts page renders the same numbers, it just can no longer render wrong ones.

1. Sign in as owner@e2etest.com (super admin) and open /platform/payouts. Balances render as before; per-currency figures unchanged against the seed data.
2. Record a manual payout for a tenant. The 10% mismatch warning still fires on a deliberately wrong amount and still stays quiet on a correct one.
3. curl -H "Authorization: Bearer $CRON_SECRET" localhost:3000/api/cron/enforce-plan-limits → same tenant tallies as before the change.
4. To see the guard itself, repeat the cap experiment above: with pgrst.db_max_rows forced below a table's row count, the page must either render complete numbers or fail loudly — never show a plausible low one.

Out of scope

Surveying for this turned up the identical unpaginated-sweep shape in six other places, all service-role, all iterating the full array: solana-reconcile, binance-personal-reconcile, expire-subscriptions, solana-pull, expire-platform-subscriptions (four separate sweeps in that one), and app/actions/platform/billing-health.ts. None is in this issue's scope and each has its own blast radius worth reasoning about separately, but they now have a helper to adopt — worth a follow-up issue. app/sitemap.xml/route.ts also asks for .limit(5000) against a 1000-row cap, which is a quieter version of the same mismatch.

🤖 Generated with Claude Code

https://claude.ai/code/session_01T6Vfwhyj4Sktx8Am54cCGz